home *** CD-ROM | disk | FTP | other *** search
/ Super Shareware Collection / Super Shareware Collection.iso / os_2 / startdos.zip / STARTDOS.RME < prev   
Text File  |  1994-02-04  |  9KB  |  222 lines
  1. STARTDOS REVISION HISTORY                                   MONTE COPELAND
  2.  
  3. 11NOV93: new api StartSeamless(); tweak readme
  4. 25OCT93: settings.exe; sprintf pid into term queue name
  5. 11OCT93: fix rexx file search bug; tweak readme
  6. 09OCT93: tweak readme; new Rexx API SetSessionTitle()
  7. 21SEP93: new Rexx API SetCommandArgs()
  8. 27AUG93: default session full screen; searches PATH environment
  9. for CMD file; startdata length changed to 32.
  10. 06MAY93: first release.
  11.  
  12.  
  13. --------------------------- STARTDOS USAGE -------------------------------
  14.  
  15. STARTDOS <Rexx CMD file> <optional command.com arguments>
  16.  
  17. Example StartDos command lines:
  18.  
  19. startdos                        prints this readme
  20. startdos sets.cmd               searches path for sets.cmd
  21. startdos sets                   adds .CMD then searches path
  22. startdos sets /c wp             /c for call; session exits with wp
  23. startdos sets /k dir            /k for keep; dir and session stays
  24.                                 /c and /k are command.com-defined switches
  25. startdos sets /c winos2 word    starts winos2 and a windows program
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32. -------------------------------- INTRODUCTION ----------------------------
  33.  
  34. StartDos is an OS/2 program to start virtual DOS mode sessions under OS/2.
  35. The nature of DOS sessions under OS/2 is controlled by DOS settings, some of
  36. which can only be set at session startup. StartDos accepts these settings via
  37. a Rexx command file then starts a DOS session. Examples of some setting
  38. strings that can only be specified at start time:
  39.  
  40.   DOS_DEVICE=<device driver file spec>
  41.   DOS_HIGH=1                                (1 means yes)
  42.   DPMI_DOS_API=ENABLED
  43.   DPMI_MEMORY_LIMIT=8                       (integer represents megabytes)
  44.  
  45. Most settings that require ON accept either ON or 1, but some settings must
  46. have a 1 instead of ON. For help with settings strings, run SETTINGS.EXE.
  47.  
  48. To specify DOS settings to StartDos, name a Rexx command file on the command
  49. line. StartDos will add .CMD if necessary. StartDos looks in the current
  50. directory for the Rexx file. If not present, it searches the PATH. StartDos
  51. invokes the Rexx interpreter, and the command file executes in a special
  52. StartDos environment. In this environment, the Rexx program can call
  53. functions in StartDos like AddDosSetting() and StartWindowed(). Example Rexx:
  54.  
  55.   /* Rexx command file for StartDos (comment mandatory on first line!) */
  56.   parse arg szCommandComArgs
  57.   if 'STARTDOS' <> address()  then do
  58.     say 'Expected STARTDOS environment'
  59.     return 2
  60.   end
  61.   rc = SetSessionTitle( 'DPMI DOS Session' )
  62.   rc = AddDosSetting( 'DOS_DEVICE=C:\OS2\MDOS\ANSI.SYS' )
  63.   rc = AddDosSetting( 'DOS_HIGH=1'  )
  64.   rc = AddDosSetting( 'DPMI_DOS_API=ENABLED' )
  65.   rc = AddDosSetting( 'DPMI_MEMORY_LIMIT=8' )
  66.   /* override the default and start the session in a text window */
  67.   rc = StartWindowed()
  68.   return 0
  69.  
  70. If sucessful, the Rexx program should return a zero result code, and StartDos
  71. will start the DOS session.
  72.  
  73.  
  74.  
  75.  
  76.  
  77. ----------------------- SPECIAL STARTDOS FUNCTIONS -----------------------
  78.  
  79. These special functions are available to Rexx programs invoked from StartDos:
  80.  
  81.   AddDosSetting( <setting string> )    /* may be called multiple times */
  82.   ExecSynchronous()                    /* asynchronous start is default */
  83.   SetCommandArgs( <command.com args> ) /* args acceptable to command.com */
  84.   SetSessionTitle( <session title> )   /* title to appear in window list */
  85.   StartBackground()                    /* start session in background */
  86.   StartForeground()                    /* foreground start is default */
  87.   StartFullscreen()                    /* fullscreen start is the default */
  88.   StartSeamless()                      /* start windows program seamlessly */
  89.   StartWindowed()                      /* start session in a text window */
  90.  
  91. AddDosSetting( <setting string> ) -- AddDosSetting may be called multiple
  92. times in order to specify all the setting strings to StartDos. Expects one
  93. string parameter.
  94.  
  95. ExecSynchronous() -- The default exec is asynchronous; i.e., StartDos will
  96. end as soon as the child DOS session is started. A synchronous exec is one
  97. where StartDos waits until the child DOS session ends before StartDos itself
  98. ends. In this case, StartDos will return the same errorlevel as COMMAND.COM.
  99. COMMAND.COM in OS/2 returns the same errorlevel as the DOS program invoked
  100. with the /c option. Therefore, a synchronous exec and /c option causes
  101. StartDos to return with the same errorlevel as the DOS program. This is
  102. important when invoking DOS programs from OS/2 make files. Expects no
  103. parameter.
  104.  
  105. SetCommandArgs( <command.com args> ) -- Parameters to COMMAND.COM may be
  106. specified two different ways: on the StartDos command line after the Rexx
  107. command file name, or by using SetCommandArgs() in the batch file.
  108. SetCommandArgs() always overrides arguments given on the StartDos command
  109. line. COMMAND.COM arguments given on the StartDos command line may be
  110. examined from the Rexx file by using PARSE ARG. NOTE: when using
  111. StartSeamless(), SetCommandArgs() sets arguments to WINOS2.COM, not
  112. COMMAND.COM. Expects one string parameter.
  113.  
  114. SetSessionTitle( <session title> ) -- Sets the session title that appears in
  115. the Window List. Expects one string parameter.
  116.  
  117. StartBackground() -- Start the DOS session in background. No parameters.
  118.  
  119. StartForeground() -- Start the DOS session in the foreground. This is the
  120. default action. No parameters.
  121.  
  122. StartFullscreen() -- Start the DOS session in its own, full screen session.
  123. This is the default action. No parameters.
  124.  
  125. StartSeamless() -- Starts a windows program seamlessly on the PM desktop. Use
  126. SetCommandArgs() to name the windows program using a command syntax
  127. acceptable to WINOS2.COM. For example, to start windows write.exe, use
  128.  
  129.   rc = StartSeamless()
  130.   rc = SetCommandArgs( "/s write" )
  131.  
  132. StartSeamless() expects no parameters.
  133.  
  134. StartWindowed() -- Start the DOS session in a PM text window. Expects no
  135. parameters.
  136.  
  137.  
  138.  
  139.  
  140. --------------------- SAMPLE REXX: CLEAN.CMD -----------------------------
  141.  
  142. Assume there is a DOS program called CLEANDSK.EXE that writes zeroes to
  143. unused sectors on a floppy disk. Using the Rexx address() function, you can
  144. write one Rexx file that senses whether it is running under CMD.EXE or
  145. STARTDOS.EXE. Under CMD, it invokes StartDos. Under StartDos, it calls the
  146. special StartDos functions.
  147.  
  148.      /* clean.cmd */
  149.      parse arg szDriveLetter .
  150.      parse source . . szRexxFileName .
  151.      select
  152.        when 'CMD' = address()  then do
  153.          'STARTDOS' szRexxFileName szDriveLetter
  154.        end
  155.        when 'STARTDOS' = address()  then do
  156.          rc = SetCommandArgs( "/c cleandsk" szDriveLetter )
  157.          rc = StartBackground()
  158.          rc = ExecSynchronous( )
  159.        end
  160.        otherwise do
  161.          say 'Unexpected execution environment'
  162.          return 4
  163.        end
  164.      end
  165.      return 0
  166.  
  167.  
  168. Then from an OS/2 prompt, enter
  169.  
  170.      CLEAN A:
  171.  
  172.  
  173. --------------------- SAMPLE REXX: SEAMLESS WINDOWS WRITE ----------------
  174.  
  175. This Rexx program starts the windows program WRITE.EXE seamlessly. For
  176. seamless starts, SetCommandArgs() really sets the arguments to WINOS2.COM. To
  177. WINOS2.COM, /s means standard mode and /3 means enhanced mode.
  178.  
  179.      /* write.cmd */
  180.      parse source . . szRexxFileName .
  181.      select
  182.        when 'CMD' = address()  then do
  183.          'STARTDOS' szRexxFileName
  184.        end
  185.        when 'STARTDOS' = address()  then do
  186.          rc = StartSeamless()
  187.          rc = SetCommandArgs( "/s write" )
  188.        end
  189.        otherwise do
  190.          say 'Unexpected execution environment'
  191.          return 4
  192.        end
  193.      end
  194.      return 0
  195.  
  196.  
  197. -------------------------- ERROR CHECKING ---------------------------------
  198.  
  199. If you specify an incorrect DOS setting, chances are the session will start
  200. anyway. You may get an error message from OS/2. StartDos itself may exit with
  201. a failed assertion.
  202.  
  203. For brevity, most of the sample Rexx shown here does not do error checking.
  204.  
  205.  
  206.  
  207.  
  208. ------------------------ NOTICE: PLEASE READ -------------------------------
  209.  
  210. You have accepted this program with the understanding that the IBM
  211. Corporation makes no representations or warranties as to the suitability of
  212. this program for your particular purpose, and to the extent you use or
  213. implement this program in your own setting, you do so at your own risk. In no
  214. event will IBM Corporation be liable for any damages, whether consequential,
  215. incidental, or special, arising out of the use or inability to use the
  216. program provided herewith. This program has restrictive terms and conditions
  217. associated with its use and reproduction to which you must agree. DO NOT POST
  218. MODIFIED VERSIONS OF THIS PROGRAM FOR PUBLIC ACCESS.
  219.  
  220. StartDos written by Monte Copeland, IBM Boca Raton.
  221. Copyright the IBM Corporation, 1993, All rights reserved.
  222.